home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / stdio / RCS / scanf.man,v < prev    next >
Text File  |  1989-01-04  |  6KB  |  313 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.2
  10. date     89.01.04.11.42.45;  author ouster;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     89.01.04.10.14.53;  author ouster;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @Add documentation for vfscanf.
  27. @
  28. text
  29. @.\"    @@(#)scanf.3s    6.1 (Berkeley) 5/15/85
  30. .\"
  31. .TH SCANF 3S  "May 15, 1985"
  32. .AT 3
  33. .SH NAME
  34. scanf, fscanf, sscanf, vfscanf \- formatted input conversion
  35. .SH SYNOPSIS
  36. .B #include <stdio.h>
  37. .PP
  38. .B scanf(format
  39. [ , pointer ] . . .
  40. .B )
  41. .br
  42. .B char *format;
  43. .PP
  44. .B fscanf(stream, format
  45. [ , pointer ] . . .
  46. .B )
  47. .br
  48. .SM
  49. .B FILE
  50. .B *stream;
  51. .br
  52. .B char *format;
  53. .PP
  54. .B sscanf(s, format
  55. [ , pointer ] . . .
  56. .B )
  57. .br
  58. .B char *s, *format;
  59. .PP
  60. .B #include <varargs.h>
  61. .PP
  62. .B vfscanf(stream, format, args)
  63. .br
  64. .B FILE *stream;
  65. .br
  66. .B char *format;
  67. .br
  68. .B va_list args;
  69. .SH DESCRIPTION
  70. .I Scanf
  71. reads from the standard input stream
  72. .BR stdin .
  73. .I Fscanf
  74. reads from the named input
  75. .IR stream .
  76. .I Sscanf
  77. reads from the character string
  78. .IR s .
  79. \fIVfscanf\fR provides an alternate form of \fIfscanf\fR in which
  80. the arguments have already been captured using the variable-length
  81. argument facilities provided by \fIvarargs(3)\fR.
  82. Each function reads characters, interprets
  83. them according to a format, and stores the results in its arguments.
  84. Each expects as arguments
  85. a control string
  86. .IR format ,
  87. described below,
  88. and a set of
  89. .I pointer
  90. arguments
  91. indicating where the converted input should be stored.
  92. .PP
  93. The
  94. control string
  95. usually contains
  96. conversion specifications, which are used to direct interpretation
  97. of input sequences.
  98. The control string may contain:
  99. .TP 4
  100. 1.
  101. Blanks, tabs or newlines,
  102. which match optional white space in the input.
  103. .TP 4
  104. 2.
  105. An ordinary character (not %) which must match
  106. the next character of the input stream.
  107. .TP 4
  108. 3.
  109. Conversion specifications, consisting of the
  110. character
  111. .BR % ,
  112. an optional assignment suppressing character
  113. .BR * ,
  114. an optional numerical maximum field width, and a conversion
  115. character.
  116. .PP
  117. A conversion specification directs the conversion of the
  118. next input field; the result
  119. is placed in the variable pointed to by the corresponding argument,
  120. unless assignment suppression was
  121. indicated by
  122. .BR * .
  123. An input field is defined as a string of non-space characters;
  124. it extends to the next inappropriate character or until the field
  125. width, if specified, is exhausted.
  126. .PP
  127. The conversion character indicates the interpretation of the
  128. input field; the corresponding pointer argument must
  129. usually be of a restricted type.
  130. The following conversion characters are legal:
  131. .TP 4
  132. .B  %
  133. a single `%' is expected
  134. in the input at this point;
  135. no assignment is done.
  136. .TP 4
  137. .B  d
  138. a decimal integer is expected;
  139. the corresponding argument should be an integer pointer.
  140. .TP 4
  141. .B  o
  142. an octal integer is expected;
  143. the corresponding argument should be a integer pointer.
  144. .TP 4
  145. .B  x
  146. a hexadecimal integer is expected;
  147. the corresponding argument should be an integer pointer.
  148. .ti -0.2i
  149. .TP 4
  150. .B  s
  151. a character string is expected;
  152. the corresponding argument should be a character pointer
  153. pointing to an array of characters large enough to accept the
  154. string and a terminating `\e0', which will be added.
  155. The input field is terminated by a space character
  156. or a newline.
  157. .TP 4
  158. .B  c
  159. a character is expected; the
  160. corresponding argument should be a character pointer.
  161. The normal skip over space characters is suppressed
  162. in this case;
  163. to read the next non-space character, try
  164. `%1s'.
  165. If a field width is given, the corresponding argument
  166. should refer to a character array, and the
  167. indicated number of characters is read.
  168. .TP 4
  169. \z\fBe\v'1'f\v'-1'\fR
  170. a
  171. floating point number is expected;
  172. the next field is converted accordingly and stored through the
  173. corresponding argument, which should be a pointer to a
  174. .IR float .
  175. The input format for
  176. floating point numbers is
  177. an optionally signed
  178. string of digits
  179. possibly containing a decimal point, followed by an optional
  180. exponent field consisting of an E or e followed by an optionally signed integer.
  181. .TP 4
  182. .B  [
  183. indicates a string not to be delimited by space characters.
  184. The left bracket is followed by a set of characters and a right
  185. bracket; the characters between the brackets define a set
  186. of characters making up the string.
  187. If the first character
  188. is not circumflex (\|^\|), the input field
  189. is all characters until the first character not in the set between
  190. the brackets; if the first character
  191. after the left bracket is ^, the input field is all characters
  192. until the first character which is in the remaining set of characters
  193. between the brackets.
  194. The corresponding argument must point to a character array.
  195. .PP
  196. The conversion characters
  197. .BR d ,
  198. .B o
  199. and
  200. .B x
  201. may be capitalized or preceded by
  202. .B l
  203. to indicate that a pointer to
  204. .B long
  205. rather than to
  206. .B int
  207. is in the argument list.
  208. Similarly, the conversion characters
  209. .B e
  210. or
  211. .B f
  212. may be capitalized or
  213. preceded by
  214. .B l
  215. to indicate a pointer to 
  216. .B double
  217. rather than to 
  218. .BR float .
  219. The conversion characters
  220. .BR d ,
  221. .B o
  222. and
  223. .B x
  224. may be preceded by
  225. .B h
  226. to indicate a pointer to
  227. .B short
  228. rather than to
  229. .BR int .
  230. .PP
  231. The
  232. .I scanf
  233. functions return the number of successfully matched and assigned input
  234. items.
  235. This can be used to decide how many input items were found.
  236. The constant
  237. .SM
  238. .B EOF
  239. is returned upon end of input; note that this is different
  240. from 0, which means that no conversion was done;
  241. if conversion was intended, it was frustrated by an
  242. inappropriate character in the input.
  243. .PP
  244. For example, the call
  245. .IP "" 10
  246. int i; float x; char name[50];
  247. .br
  248. scanf("%d%f%s", &i, &x, name);
  249. .PP
  250. with the input line
  251. .IP
  252. 25   54.32E\(mi1  thompson
  253. .PP
  254. will assign to
  255. .I i
  256. the value
  257. 25,
  258. .I x
  259. the value 5.432, and
  260. .I name
  261. will contain
  262. .IR `thompson\e0' .
  263. Or,
  264. .IP
  265. int i; float x; char name[50];
  266. .br
  267. scanf("%2d%f%*d%[1234567890]", &i, &x, name);
  268. .PP
  269. with input
  270. .IP
  271. 56789 0123 56a72
  272. .PP
  273. will assign 56 to
  274. .IR i ,
  275. 789.0 to
  276. .IR x ,
  277. skip `0123',
  278. and place the string `56\e0' in
  279. .IR name .
  280. The next call to
  281. .I getchar
  282. will return `a'.
  283. .SH "SEE ALSO"
  284. atof(3),
  285. getc(3S),
  286. printf(3S)
  287. .SH DIAGNOSTICS
  288. The 
  289. .I scanf
  290. functions return
  291. .SM
  292. .B EOF
  293. on end of input,
  294. and a short count for missing or illegal data items.
  295. .SH BUGS
  296. The success of literal matches and suppressed
  297. assignments is not directly
  298. determinable.
  299. @
  300.  
  301.  
  302. 1.1
  303. log
  304. @Initial revision
  305. @
  306. text
  307. @d6 1
  308. a6 1
  309. scanf, fscanf, sscanf \- formatted input conversion
  310. d31 10
  311. d51 3
  312. @
  313.